<?php

/**
 * This file is part of Switcher.
 * 
 * Switcher is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 * 
 * Switcher is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 * 
 * You should have received a copy of the GNU General Public License
 * along with Switcher. If not, see <http://www.gnu.org/licenses/>.
 * 
 * @license http://www.opensource.org/licenses/gpl-3.0.html GPL-3.0
 */

namespace switcher\filters;

/**
 * The <b>Filter</b> class doesn't fit any part of the MVC pattern. It is rather a technical
 * class designed for tranversal issues handling. A <i>filter</i> has the ability to filter
 * both the user input and the Switcher output. By default, <i>filters</i> apply to all views.
 * 
 * <p>This is the base class of all filters. User-defined filters must extend this class
 * or any subclass. Two abstract methods must be implemented for both request and response
 * filtering phases. It is possible to use Switcher exceptions for special cases. A filter
 * for authentication might for example throw a <b>ForwardException</b> to redirect unknown
 * users to a <i>login</i> page before allowing to browse the rest of the application.</p>
 *
 * @author Dri <switcher.framework@gmail.com>
 * @license http://www.opensource.org/licenses/gpl-3.0.html GPL-3.0
 * @package switcher\filters
 * @since 1.0.0
 * @see FilterStack
 * @see RequestFilter
 * @see ResponseFilter
 * @see switcher\exceptions\BadRequestException
 * @see switcher\exceptions\ForbiddenException
 * @see switcher\exceptions\ForwardException
 * @see switcher\exceptions\NotFoundException
 * @see switcher\exceptions\RedirectException
 */
abstract class Filter
{
	/**
	 * The root path to the current application.
	 * @var string
	 */
	protected $root;
	
	/**
	 * Logger.
	 * @var switcher\log\Logger
	 */
	protected $logger;
	
	/**
	 * No-arg constructor.
	 */
	public final function __construct()
	{
	}
	
	/**
	 * Filters the user's request. Filtering the user's request should rely on global
	 * variables such as $_SERVER, $_SESSION, $_GET, $_POST and $_FILES.
	 */
	public abstract function doFilterRequest();
	
	/**
	 * Filters the application's response.
	 * 
	 * @param string $response The original response
	 * @return string The filtered response
	 */
	public abstract function doFilterResponse($response);
}

?>